Diffuse initialization
======================

State-space models with a nonstationary (unit-root) state -- a random walk, a
stochastic trend, an integrated process -- have no finite unconditional variance
for the diffuse directions, so the Kalman filter needs a *diffuse* initial
condition. RISE selects the initial covariance through the option
``kf_init_variance``:

``[]`` (default)
    The unconditional (Lyapunov) variance for the stationary states and
    ``lyapunov_diffuse_factor`` for the nonstationary ones.

a positive scalar :math:`\kappa`
    Harvey's large-variance approximation: put :math:`\kappa` on all states,
    optionally discarding a presample (``kf_presample``) while the diffuseness
    washes out.

``'exact'``
    The exact Durbin--Koopman diffuse filter: the diffuse directions are resolved
    in a short, exact diffuse phase and the likelihood is :math:`\kappa`-free.

Why prefer exact
----------------

The big-:math:`\kappa` likelihood carries a spurious offset
:math:`-\tfrac{q}{2}\log(2\pi\kappa)` (with :math:`q` the number of diffuse
directions) that *depends on* :math:`\kappa`. It therefore contaminates the
log-likelihood, the marginal data density, and any model comparison. Exact
initialization removes it: there is no :math:`\kappa` to choose, no presample to
discard, and no conditioning penalty (big-:math:`\kappa` also loses accuracy as
:math:`\kappa` grows and the covariance becomes ill-conditioned).

Usage
-----

::

    m = solve(dsge_model('mymodel.rs'));
    m = set(m, 'data', db);
    [~, loglik] = filter(m, 'kf_init_variance', 'exact');   % 2nd output is the loglik

``filter`` returns ``[filtration, LogLik, Incr, retcode, obj]``. Use
``kf_presample = 0`` if you want the diffuse-period term *included* in the
likelihood (a presample discards it).

Scope
-----

Exact diffuse initialization is available in the interacting-multiple-model
(``imm``, the default) engine and in the GPB-family regime-switching filters
``immn``, ``kim_nelson`` and ``gpbn``. It works for both **constant-parameter**
and **regime-switching** models -- a single-regime model is routed to ``imm`` by
default. To use one of the GPB filters, pin it with ``kf_user_algo`` (for example
``filter(m, 'kf_init_variance', 'exact', 'kf_user_algo', @rise.engine.filtering.kim_nelson)``);
all four give the same diffuse loglik. If a filter that does **not** implement
exact is pinned (e.g. ``imm_o`` or the constrained cell filter), RISE warns and
falls back to big-:math:`\kappa`; those may gain exact support in future.

Exact diffuse is valid for the **regular** case: a diffuse block that is the same
across regimes (a shared trend or unit root, with switching confined to transitory
dynamics, loadings, or shock variances). Two guards keep it there. If the
nonstationary invariant subspace differs across regimes (a **regime-dependent**
diffuse block), or if the measurement-noise covariance :math:`H` is **non-diagonal**
(the univariate diffuse cascade assumes a diagonal :math:`H`), RISE warns and falls
back to big-:math:`\kappa` rather than return a silently-wrong likelihood. The
regime-dependent case is the home of the augmented (de Jong) formulation, which is
derived but not yet implemented.

Smoothing over the diffuse period: ``kim_nelson`` runs a Durbin--Koopman
dual-accumulator backward recursion across the diffuse span. The shared
regime-switching smoother of ``imm``, ``immn`` and ``gpbn`` smooths the diffuse
steps pairwise too, with the updated covariance :math:`P_* + \kappa P_\infty`,
:math:`\kappa = 10^8`: the exact-diffuse limit to :math:`O(1/\kappa)`.

The diffuse subspace is the nonstationary **invariant subspace** of the state
transition, computed from an ordered real Schur decomposition, so it is correct
not only for a random walk but for **multiple** and **defective** unit roots --
e.g. a local linear trend, whose transition ``[1 1; 0 1]`` is a Jordan block with
a two-dimensional diffuse subspace but a single eigenvector.

The worked example ``Estimation/diffuse_initialization/howto.m`` in the tutorials
prints the :math:`\kappa`-offset and demonstrates its removal
(``ll_bigk + \tfrac{q}{2}\log\kappa \to ll_{exact}`` at rate :math:`O(1/\kappa)`).

.. note::

   Reference: Durbin, J. and Koopman, S. J. (2012), *Time Series Analysis by State
   Space Methods*, 2nd ed., ch. 5 (the exact initial Kalman filter).